<!DOCTYPE html>
<html>
<!-- Created by GNU Texinfo 7.1, https://www.gnu.org/software/texinfo/ -->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<!-- Copyright © 1988-2023 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with the
Invariant Sections being "Funding Free Software", the Front-Cover
Texts being (a) (see below), and with the Back-Cover Texts being (b)
(see below).  A copy of the license is included in the section entitled
"GNU Free Documentation License".

(a) The FSF's Front-Cover Text is:

A GNU Manual

(b) The FSF's Back-Cover Text is:

You have freedom to copy and modify this GNU Manual, like GNU
     software.  Copies published by the Free Software Foundation raise
     funds for GNU development. -->
<title>Option file format (GNU Compiler Collection (GCC) Internals)</title>

<meta name="description" content="Option file format (GNU Compiler Collection (GCC) Internals)">
<meta name="keywords" content="Option file format (GNU Compiler Collection (GCC) Internals)">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta name="viewport" content="width=device-width,initial-scale=1">

<link href="index.html" rel="start" title="Top">
<link href="Option-Index.html" rel="index" title="Option Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="Options.html" rel="up" title="Options">
<link href="Option-properties.html" rel="next" title="Option properties">
<style type="text/css">
<!--
a.copiable-link {visibility: hidden; text-decoration: none; line-height: 0em}
span:hover a.copiable-link {visibility: visible}
ul.mark-bullet {list-style-type: disc}
-->
</style>


</head>

<body lang="en">
<div class="section-level-extent" id="Option-file-format">
<div class="nav-panel">
<p>
Next: <a href="Option-properties.html" accesskey="n" rel="next">Option properties</a>, Up: <a href="Options.html" accesskey="u" rel="up">Option specification files</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Option-Index.html" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<h3 class="section" id="Option-file-format-1"><span>8.1 Option file format<a class="copiable-link" href="#Option-file-format-1"> &para;</a></span></h3>

<p>Option files are a simple list of records in which each field occupies
its own line and in which the records themselves are separated by
blank lines.  Comments may appear on their own line anywhere within
the file and are preceded by semicolons.  Whitespace is allowed before
the semicolon.
</p>
<p>The files can contain the following types of record:
</p>
<ul class="itemize mark-bullet">
<li>A language definition record.  These records have two fields: the
string &lsquo;<samp class="samp">Language</samp>&rsquo; and the name of the language.  Once a language
has been declared in this way, it can be used as an option property.
See <a class="xref" href="Option-properties.html">Option properties</a>.

</li><li>A target specific save record to save additional information. These
records have two fields: the string &lsquo;<samp class="samp">TargetSave</samp>&rsquo;, and a
declaration type to go in the <code class="code">cl_target_option</code> structure.

</li><li>A variable record to define a variable used to store option
information.  These records have two fields: the string
&lsquo;<samp class="samp">Variable</samp>&rsquo;, and a declaration of the type and name of the
variable, optionally with an initializer (but without any trailing
&lsquo;<samp class="samp">;</samp>&rsquo;).  These records may be used for variables used for many
options where declaring the initializer in a single option definition
record, or duplicating it in many records, would be inappropriate, or
for variables set in option handlers rather than referenced by
<code class="code">Var</code> properties.

</li><li>A variable record to define a variable used to store option
information.  These records have two fields: the string
&lsquo;<samp class="samp">TargetVariable</samp>&rsquo;, and a declaration of the type and name of the
variable, optionally with an initializer (but without any trailing
&lsquo;<samp class="samp">;</samp>&rsquo;).  &lsquo;<samp class="samp">TargetVariable</samp>&rsquo; is a combination of &lsquo;<samp class="samp">Variable</samp>&rsquo;
and &lsquo;<samp class="samp">TargetSave</samp>&rsquo; records in that the variable is defined in the
<code class="code">gcc_options</code> structure, but these variables are also stored in
the <code class="code">cl_target_option</code> structure.  The variables are saved in the
target save code and restored in the target restore code.

</li><li>A variable record to record any additional files that the
<samp class="file">options.h</samp> file should include.  This is useful to provide
enumeration or structure definitions needed for target variables.
These records have two fields: the string &lsquo;<samp class="samp">HeaderInclude</samp>&rsquo; and the
name of the include file.

</li><li>A variable record to record any additional files that the
<samp class="file">options.cc</samp> or <samp class="file">options-save.cc</samp> file should include.  This
is useful to provide
inline functions needed for target variables and/or <code class="code">#ifdef</code>
sequences to properly set up the initialization.  These records have
two fields: the string &lsquo;<samp class="samp">SourceInclude</samp>&rsquo; and the name of the
include file.

</li><li>An enumeration record to define a set of strings that may be used as
arguments to an option or options.  These records have three fields:
the string &lsquo;<samp class="samp">Enum</samp>&rsquo;, a space-separated list of properties and help
text used to describe the set of strings in <samp class="option">--help</samp> output.
Properties use the same format as option properties; the following are
valid:
<dl class="table">
<dt><code class="code">Name(<var class="var">name</var>)</code></dt>
<dd><p>This property is required; <var class="var">name</var> must be a name (suitable for use
in C identifiers) used to identify the set of strings in <code class="code">Enum</code>
option properties.
</p>
</dd>
<dt><code class="code">Type(<var class="var">type</var>)</code></dt>
<dd><p>This property is required; <var class="var">type</var> is the C type for variables set
by options using this enumeration together with <code class="code">Var</code>.
</p>
</dd>
<dt><code class="code">UnknownError(<var class="var">message</var>)</code></dt>
<dd><p>The message <var class="var">message</var> will be used as an error message if the
argument is invalid; for enumerations without <code class="code">UnknownError</code>, a
generic error message is used.  <var class="var">message</var> should contain a single
&lsquo;<samp class="samp">%qs</samp>&rsquo; format, which will be used to format the invalid argument.
</p></dd>
</dl>

</li><li>An enumeration value record to define one of the strings in a set
given in an &lsquo;<samp class="samp">Enum</samp>&rsquo; record.  These records have two fields: the
string &lsquo;<samp class="samp">EnumValue</samp>&rsquo; and a space-separated list of properties.
Properties use the same format as option properties; the following are
valid:
<dl class="table">
<dt><code class="code">Enum(<var class="var">name</var>)</code></dt>
<dd><p>This property is required; <var class="var">name</var> says which &lsquo;<samp class="samp">Enum</samp>&rsquo; record
this &lsquo;<samp class="samp">EnumValue</samp>&rsquo; record corresponds to.
</p>
</dd>
<dt><code class="code">String(<var class="var">string</var>)</code></dt>
<dd><p>This property is required; <var class="var">string</var> is the string option argument
being described by this record.
</p>
</dd>
<dt><code class="code">Value(<var class="var">value</var>)</code></dt>
<dd><p>This property is required; it says what value (representable as
<code class="code">int</code>) should be used for the given string.
</p>
</dd>
<dt><code class="code">Canonical</code></dt>
<dd><p>This property is optional.  If present, it says the present string is
the canonical one among all those with the given value.  Other strings
yielding that value will be mapped to this one so specs do not need to
handle them.
</p>
</dd>
<dt><code class="code">DriverOnly</code></dt>
<dd><p>This property is optional.  If present, the present string will only
be accepted by the driver.  This is used for cases such as
<samp class="option">-march=native</samp> that are processed by the driver so that
&lsquo;<samp class="samp">gcc -v</samp>&rsquo; shows how the options chosen depended on the system on
which the compiler was run.
</p>
</dd>
<dt><code class="code">Set(<var class="var">number</var>)</code></dt>
<dd><p>This property is optional, required for enumerations used in
<code class="code">EnumSet</code> options.  <var class="var">number</var> should be decimal number between
1 and 64 inclusive and divides the enumeration into a set of
sets of mutually exclusive arguments.  Arguments with the same
<var class="var">number</var> can&rsquo;t be specified together in the same option, but
arguments with different <var class="var">number</var> can.  <var class="var">value</var> needs to be
chosen such that a mask of all <var class="var">value</var> values from the same set
<var class="var">number</var> bitwise ored doesn&rsquo;t overlap with masks for other sets.
When <code class="code">-foption=arg_from_set1,arg_from_set4</code> and
<code class="code">-fno-option=arg_from_set3</code> are used, the effect is that previous
value of the <code class="code">Var</code> will get bits from set 1 and 4 masks cleared,
ored <code class="code">Value</code> of <code class="code">arg_from_set1</code> and <code class="code">arg_from_set4</code>
and then will get bits from set 3 mask cleared.
</p></dd>
</dl>

</li><li>An option definition record.  These records have the following fields:
<ol class="enumerate">
<li> the name of the option, with the leading &ldquo;-&rdquo; removed
</li><li> a space-separated list of option properties (see <a class="pxref" href="Option-properties.html">Option properties</a>)
</li><li> the help text to use for <samp class="option">--help</samp> (omitted if the second field
contains the <code class="code">Undocumented</code> property).
</li></ol>

<p>By default, all options beginning with &ldquo;f&rdquo;, &ldquo;g&rdquo;, &ldquo;W&rdquo; or &ldquo;m&rdquo; are
implicitly assumed to take a &ldquo;no-&rdquo; form.  This form should not be
listed separately.  If an option beginning with one of these letters
does not have a &ldquo;no-&rdquo; form, you can use the <code class="code">RejectNegative</code>
property to reject it.
</p>
<p>The help text is automatically line-wrapped before being displayed.
Normally the name of the option is printed on the left-hand side of
the output and the help text is printed on the right.  However, if the
help text contains a tab character, the text to the left of the tab is
used instead of the option&rsquo;s name and the text to the right of the
tab forms the help text.  This allows you to elaborate on what type
of argument the option takes.
</p>
<p>There is no support for different help texts for different languages.
If an option is supported for multiple languages, use a generic
description that is correct for all of them.
</p>
<p>If an option has multiple option definition records (in different
front ends&rsquo; <samp class="file">*.opt</samp> files, and/or <samp class="file">gcc/common.opt</samp>, for
example), convention is to not duplicate the help text for each of
them, but instead put a comment like <code class="code">; documented in common.opt</code>
in place of the help text for all but one of the multiple option
definition records.
</p>
</li><li>A target mask record.  These records have one field of the form
&lsquo;<samp class="samp">Mask(<var class="var">x</var>)</samp>&rsquo;.  The options-processing script will automatically
allocate a bit in <code class="code">target_flags</code> (see <a class="pxref" href="Run_002dtime-Target.html">Run-time Target Specification</a>) for
each mask name <var class="var">x</var> and set the macro <code class="code">MASK_<var class="var">x</var></code> to the
appropriate bitmask.  It will also declare a <code class="code">TARGET_<var class="var">x</var></code>
macro that has the value 1 when bit <code class="code">MASK_<var class="var">x</var></code> is set and
0 otherwise.

<p>They are primarily intended to declare target masks that are not
associated with user options, either because these masks represent
internal switches or because the options are not available on all
configurations and yet the masks always need to be defined.
</p></li></ul>

</div>
<hr>
<div class="nav-panel">
<p>
Next: <a href="Option-properties.html">Option properties</a>, Up: <a href="Options.html">Option specification files</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Option-Index.html" title="Index" rel="index">Index</a>]</p>
</div>



</body>
</html>
